home *** CD-ROM | disk | FTP | other *** search
/ Best of Shareware / Best of PC Windows Shareware 1.0 - Wayzata Technology (7111) (1993).iso / mac / DOS / UTILITY / ZIPFND12 / ZIPFIND.DOC < prev    next >
Text File  |  1992-09-25  |  19KB  |  456 lines
  1.  
  2.  
  3.                                  ZIPFIND Ver. 1.2
  4.                         Copyright (c) 1991-1992 Mike Albert
  5.                                   September 1992
  6.  
  7.  
  8.  
  9.      1   INTRODUCTION
  10.  
  11.      ZIPFIND searches ZIP or ARC files for text strings.  ZIPFIND displays
  12.      each line of each archived file that contains the desired string, and
  13.      provides the following benefits:
  14.  
  15.          o   Any type of file stored in an ARC or ZIP file can be searched
  16.              for any text string.
  17.  
  18.          o   You can use your own text search program to provide more
  19.              powerful search options.  Many programs (e.g. GREP variants)
  20.              provide pattern searches and special output options not
  21.              otherwise available.
  22.  
  23.  
  24.  
  25.      2   OPERATION
  26.  
  27.      To search an ARC or ZIP file for a string:
  28.  
  29.          zipfind  [options]  "searchstring"  filespec
  30.  
  31.      where:
  32.  
  33.          [options]
  34.              is zero or more MS-DOS FIND command options.  In version 5.0 of
  35.              MS-DOS the options are:
  36.  
  37.              /v      Display lines that do NOT contain the search string.
  38.  
  39.              /c      Display the number of lines that contain the search
  40.                      string, but not the lines themselves.
  41.  
  42.              /n      Display the line number beside each line.
  43.  
  44.              /i      Ignore the case of characters when comparing.
  45.  
  46.              See the MS-DOS User's Reference for more information on these
  47.              options.  If you use your own text search program, use its
  48.              options instead of these.
  49.  
  50.          "searchstring"
  51.              is the string to look for.  Quotes must surround the string if
  52.              it contains blanks or other white space characters, or the
  53.              characters ">", "<", or "|".
  54.  
  55.          filespec
  56.              lists the names of one or more ARC or ZIP files to search.  Use
  57.              wildcard characters ("?" and "*") to specify groups of files.
  58.              If you specify a file name without an extension, ZIPFIND
  59.              searches both ARC and ZIP files.  If you specify a directory,
  60.              ZIPFIND searches all ARC and ZIP files in the directory.
  61.  
  62.  
  63.  
  64.  
  65.  
  66.                                        - 1 -
  67.  
  68.      ZIPFIND normally displays its results on the screen, but you can use
  69.      MS-DOS output redirection (via ">", ">>", or "|" on the command line) to
  70.      direct the search listing to a file or another program.
  71.  
  72.      The following examples illustrate the use of ZIPFIND:
  73.  
  74.          Search ZIP file letters.zip for the string "Pam":
  75.  
  76.              ZIPFIND  Pam  letters.zip
  77.  
  78.  
  79.          Search ARC files letters.arc and back.arc and ZIP files letters.zip
  80.          and back.zip for the string "IBM".  Use the /i option so that case
  81.          is ignored when comparing and the /c option so that only the number
  82.          of matching lines is shown:
  83.  
  84.              ZIPFIND  /i  /c  "IBM"  letters  back
  85.  
  86.  
  87.          Search all ARC files and all ZIP files in the current directory for
  88.          the string "Mike Albert".  Direct the results to file find.txt
  89.          instead of the screen.  Use the /i option so that case is ignored
  90.          when comparing:
  91.  
  92.              ZIPFIND  /i  "Mike Albert"  .  >find.txt
  93.  
  94.  
  95.  
  96.      3   ADVANCED USE
  97.  
  98.      ZIPFIND can use a text search program you provide instead of the MS-DOS
  99.      FIND command.  When ZIPFIND uses your program, you must specify options
  100.      recognized by your program, not MS-DOS FIND.  Also, if your program
  101.      expects the search string before the options on the command line, then
  102.      enter the arguments in that order.
  103.  
  104.      To use your own program, name it grep.com or grep.exe and place it in a
  105.      library on your search path.  ZIPFIND will use your program instead of
  106.      FIND.
  107.  
  108.      See the next section for search program requirements.
  109.  
  110.  
  111.  
  112.      4   ZIPFIND REQUIREMENTS
  113.  
  114.      ZIPFIND can be used on any IBM-compatible computer running under MS-DOS
  115.      versions 2.0 and later.
  116.  
  117.      ZIPFIND uses pkxarc to process ARC files and pkunzip to process ZIP
  118.      files, so these programs must be available as needed in libraries on
  119.      your search path.  Both programs are produced by PKWARE Inc. and are
  120.      available on CompuServe and other BBS's.
  121.  
  122.      ZIPFIND places temporary files in a work directory, and requires enough
  123.      free space to store the largest archived file to be searched.  ZIPFIND
  124.      uses the TEMP or TMP environment variable to locate this directory.  If
  125.      neither variable is defined, ZIPFIND uses the current directory.  Unless
  126.      there's an error, ZIPFIND deletes the directory and all temporary files
  127.      when it finishes.  If an error occurs ZIPFIND does not delete the files,
  128.  
  129.  
  130.  
  131.                                       - 2 -
  132.  
  133.      so you can examine them to analyze the problem.  The name of the work
  134.      directory is $@ZIPF@$.DIR.
  135.  
  136.      ZIPFIND is designed to work with many different text search programs,
  137.      but it does impose some requirements, i.e.:
  138.  
  139.          The program must support output redirection (i.e. the ">" command
  140.          line option).  Programs that output only to the screen can't be
  141.          used.
  142.  
  143.          The program must accept arguments in the order:
  144.             "searchstring"  [options]  filespec
  145.          or
  146.             [options]  "searchstring"  filespec
  147.          Note that in both cases the filespec is last.
  148.  
  149.          Options must start with either "-" or "/", e.g. the "i" option must
  150.          be specified as either "/i" or "-i".
  151.  
  152.          When the program lists the name of a file, it must show the path
  153.          name as it was passed to it on the command line.  In particular,
  154.          when a full path name in upper case letters without wild cards is
  155.          specified, the listing must identify the file in exactly the same
  156.          way.
  157.  
  158.  
  159.      ZIPFIND has been successfully tested with the following text search
  160.      programs:
  161.  
  162.          GGREP by Sam Baxter (available on CompuServe in forum IBMSYS,
  163.          Library 3, file ggrep.arc).
  164.  
  165.          FGREP by Christopher Dunford (available on CompuServe in forum
  166.          IBMAPP, Library 2, file fgrep.arc).
  167.  
  168.          GREP by DECUS, Kern, Smith, and Brigs (available on CompuServe in
  169.          forum IBMAPP, Library 2, file grep.arc).
  170.  
  171.          GREP by Borland International Inc. (packaged with Borland language
  172.          products).
  173.  
  174.  
  175.      ZIPFIND does not work with the following program:
  176.  
  177.          Text Search by Peter Norton (output redirection is not supported and
  178.          the file name is the first argument).
  179.  
  180.  
  181.  
  182.      5   ZIPFIND MESSAGES
  183.  
  184.          ZIPFIND Error: <x> is not an ARC or ZIP file.
  185.              ZIPFIND only processes ARC and ZIP files.  You specified file
  186.              <x> that has an extension other than .arc or .zip.
  187.  
  188.          ZIPFIND Error: Couldn't create directory <x>.
  189.              ZIPFIND tried to create directory <x> and was unsuccessful.
  190.              Check if <x> is a legal place to create a directory.  If not,
  191.              look at the TEMP or TMP environment variables which ZIPFIND used
  192.              to determine <x> and change which ever one is present to
  193.  
  194.  
  195.  
  196.                                       - 3 -
  197.  
  198.              indicate a legal directory.  If this fails, contact ZIPFIND
  199.              support.
  200.  
  201.          ZIPFIND Error: Couldn't redirect standard input.
  202.          ZIPFIND Error: Couldn't redirect standard output.
  203.              ZIPFIND tried to redirect the standard input or standard output
  204.              for an archive or find program to a file and was unsuccessful.
  205.              This problem should not occur under normal operation.  Contact
  206.              ZIPFIND support.
  207.  
  208.          ZIPFIND Error: Couldn't find archive program <x>.
  209.              ZIPFIND couldn't find program <x> which is needed to unarchive a
  210.              file.  Make sure that you have program <x> on your system, and
  211.              that its library is on your search path.  You can view your
  212.              search path by typing "path" at the MS-DOS prompt; the directory
  213.              that contains <x> should be listed.  If it isn't, edit your
  214.              autoexec.bat file to add the needed library to the path
  215.              statement and reboot your system.  If this fails, contact
  216.              ZIPFIND support.
  217.  
  218.          ZIPFIND Error: Couldn't find find.com, find.exe, grep.com, or
  219.          grep.exe.
  220.              ZIPFIND couldn't locate a text search program.  If you want to
  221.              use your own text search program, make sure that it's named
  222.              grep.com or grep.exe and that its library is in your search
  223.              path.  If you want to use the MS-DOS FIND command, make sure
  224.              that the MS-DOS directory (usually named MSDOS or DOS) is on
  225.              your search path, and that find.com or find.exe hasn't been
  226.              deleted from that directory.  If this fails, contact ZIPFIND
  227.              support.
  228.  
  229.          ZIPFIND Error: Couldn't interpret archive program listing file <x>.
  230.              ZIPFIND couldn't interpret the listing in file <x> produced when
  231.              it ran the archive program to list the archive contents.  This
  232.              could occur if you have a new version of the archive program
  233.              that ZIPFIND doesn't support, or if the files pkxarc.exe or
  234.              pkunzip.exe aren't the real archive programs.  Since an error
  235.              occurred ZIPFIND did not delete the listing file, so you can
  236.              examine it to see what is wrong.  If this fails, contact ZIPFIND
  237.              support for assistance.
  238.  
  239.          ZIPFIND Error: Couldn't make archiver response file <x>.
  240.              ZIPFIND tried to create file <x> and was unsuccessful.  This
  241.              problem should not occur under normal operation.  Contact
  242.              ZIPFIND support for assistance.
  243.  
  244.          ZIPFIND Error: Couldn't open archive program listing file <x>.
  245.          ZIPFIND Error: Couldn't open find program listing file <x>.
  246.              ZIPFIND tried to open file <x> which it previously created and
  247.              was unsuccessful.  This problem should not occur under normal
  248.              operation.  Contact ZIPFIND support for assistance.
  249.  
  250.          ZIPFIND Error: Insufficient disk space at <x>. File <y> only
  251.          partially searched.
  252.              ZIPFIND tried to create a file in directory <x> and couldn't
  253.              because of insufficient space.  ZIPFIND was only able to search
  254.              part of file <y>, so it might have missed a matching string.  If
  255.              there's more space on a different drive, change the TEMP or TMP
  256.              environment variable to indicate that drive.  If this fails,
  257.              contact ZIPFIND support.
  258.  
  259.  
  260.  
  261.                                       - 4 -
  262.  
  263.          ZIPFIND Error: Insufficient memory.
  264.          ZIPFIND Error: Spawn to "<x>" failed; insufficient memory.
  265.              ZIPFIND needs more memory to run.  Since ZIPFIND requires
  266.              relatively little memory, you probably have run into this
  267.              problem with other programs and know what to do.  If you don't
  268.              know what to do, contact ZIPFIND support.
  269.  
  270.          ZIPFIND Error: Internal error - insufficient buffer size.
  271.              ZIPFIND ran out of internal buffer space.  This error should not
  272.              occur in normal operation.  Contact ZIPFIND support.
  273.  
  274.          ZIPFIND Error: Spawn to "<x>" failed; errno=<y>.
  275.              ZIPFIND tried to spawn program <x> and failed.  The spawn
  276.              returned an error code of <y>.  If you're familiar with MS-DOS
  277.              error codes, you can look up the code to determine what went
  278.              wrong.  Otherwise, contact ZIPFIND support.
  279.  
  280.          ZIPFIND Error: User aborted program.
  281.              You used Ctrl-C or Ctrl-Break to abort ZIPFIND before it
  282.              finished normally.
  283.  
  284.          ZIPFIND Error: You must identify at least one file to search.
  285.              When you invoked ZIPFIND you didn't specify the files to search
  286.              on the command line.  You must specify the search string
  287.              followed by at least one file or directory specification.
  288.  
  289.          ZIPFIND Error: "<x>" returned error code <y>.
  290.              ZIPFIND spawned archive program <x> to access an archive, but it
  291.              indicated a problem by returning error code <y>.  If ZIPFIND
  292.              recognizes the error code, it displays a description of the
  293.              error in the message.  If not, look up the error code in the
  294.              documentation provided with your archive program to determine
  295.              the problem.  Since an error occurred ZIPFIND did not delete the
  296.              archive program listing file, so you can examine it (in the
  297.              ZIPFIND work directory $@ZIPF@$.DIR) to see what is wrong.  You
  298.              can also rerun the command manually and examine the results.  If
  299.              this fails, contact ZIPFIND support.
  300.  
  301.  
  302.  
  303.      6   LICENSING, WARRANTY, REGISTRATION, and SUPPORT
  304.  
  305.      ZIPFIND is distributed as shareware.  I encourage you to try ZIPFIND and
  306.      share it with friends as long as:
  307.  
  308.          The ZIPFIND program and this documentation file are not modified and
  309.          are distributed together.
  310.  
  311.          ZIPFIND is not provided as a part of any other product.
  312.  
  313.          No fees, beyond a reasonable fee for media, duplication, or
  314.          downloading costs, are charged.
  315.  
  316.          ZIPFIND is not used for commercial, government, or business purposes
  317.          without registration.  Each registration is for a single person or a
  318.          single computer.
  319.  
  320.      If you find ZIPFIND useful and decide to use it regularly, you are
  321.      required to register.  All registration payments will be donated to
  322.      Oxfam America, an international development and disaster relief agency.
  323.  
  324.  
  325.  
  326.                                       - 5 -
  327.  
  328.      It's a worthy charity that I've been supporting for many years.  For
  329.      more information on Oxfam see section 7.
  330.  
  331.      When you register you get the satisfaction of saving lives in Africa,
  332.      Asia, and South America, and encourage me to produce more software at
  333.      reasonable prices.  You also get the following benefits:
  334.  
  335.          I'll notify you of new ZIPFIND versions when they become available.
  336.  
  337.          I'll send an updated version of ZIPFIND (and my other shareware
  338.          products) to you at no additional cost.  You can request this at any
  339.          time.  I'll do this once per registered user.
  340.  
  341.          I'll answer any questions you have on ZIPFIND and its use.  You can
  342.          contact me at the address shown below or via CompuServe mail.
  343.  
  344.          If any important bugs are found I will notify you.
  345.  
  346.          I'll make an attempt (but can't guarantee) to fix any problems you
  347.          find.
  348.  
  349.      Registration is $25.  Please make your check payable to Oxfam America -
  350.      I'll send your checks to Oxfam and record your registration information.
  351.      I'll also accept original canceled checks or receipts from Oxfam that
  352.      list you as the donor.  Please send payments, registration information,
  353.      and any other correspondence to:
  354.  
  355.                 Mike Albert
  356.                 P. O. Box 535
  357.                 Bedford, MA   01730
  358.  
  359.      I can also be reached via CompuServe mail; my userid is [70325,1134].
  360.  
  361.      Anyone can order the latest version of ZIPFIND directly from me for a
  362.      fee of $5.00.  Just send the order (make sure it contains your mailing
  363.      address) with your check to the above address.  You'll receive a 5 1/4
  364.      inch 360Kb floppy disk containing the executable and documentation
  365.      files.  If you need other formats (5 1/4 inch 1.2Mb or 3 1/2 inch 720Kb
  366.      or 1.44Mb) I can provide them.  I'll also include other shareware
  367.      products I produce.  If you live outside North America, please send
  368.      extra money for the increased postage.
  369.  
  370.      I welcome all comments and suggestions concerning ZIPFIND.  I'd like to
  371.      know how you are using ZIPFIND, where you obtained it, and what
  372.      problems, bugs, or weaknesses you find.  If you tell me about
  373.      enhancements or changes you're interested in, I'll make an effort to
  374.      provide them.
  375.  
  376.      This program is provided "as is" without warranty of any kind, either
  377.      express or implied, but not limited to the implied warranties of
  378.      merchantability or fitness for a particular purpose.  The entire risk as
  379.      to the results and performance of the program is assumed by the user.
  380.      Should the program prove defective, the user assumes the entire cost of
  381.      all necessary servicing, repair, or correction.
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.                                       - 6 -
  392.  
  393.      7   OXFAM AMERICA
  394.  
  395.      As stated in Oxfam literature,
  396.  
  397.          "Oxfam America is an international agency that funds self-help
  398.          development projects and disaster relief in poor countries in
  399.          Africa, Asia, and Latin America, and also prepares and distributes
  400.          educational materials for people in the United States on the issues
  401.          of development and hunger.  The name "Oxfam" comes from the Oxford
  402.          Committee for Famine Relief, founded in England in 1942.  Oxfam
  403.          America, based in Boston, was formed in 1970, and is one of seven
  404.          autonomous Oxfams around the world (Great Britain, Australia,
  405.          Belgium, Canada, Quebec, Hong Kong and the United States).  Oxfam is
  406.          a nonsectarian, nonprofit agency that neither seeks or accepts U.S.
  407.          government funds.  All contributions are tax-deductible to the
  408.          extent permitted by law."
  409.  
  410.      For more information, you can phone Oxfam at 617-482-1211, or write to
  411.      them at:
  412.  
  413.                   Oxfam America
  414.                   26 West Street
  415.                   Boston, MA  02111-1206
  416.  
  417.  
  418.  
  419.      8   ZIPFIND REVISION HISTORY
  420.  
  421.          ZIPFIND version 1.2 - 9/25/92
  422.  
  423.              Updated documentation to show new mailing address and CompuServe
  424.              contact information.
  425.  
  426.  
  427.          ZIPFIND version 1.1 - 4/25/92
  428.  
  429.              Changed ZIPFIND to work with version 1.93 of PKUNZIP.
  430.  
  431.  
  432.          ZIPFIND version 1.0 - 12/5/91
  433.  
  434.              Initial release of ZIPFIND program.
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.                                       - 7 -